iziBasic-manual

Files

iziBasic is limited to work on database files (pdb), it does not work on program files (prc). It is even limited to work on specific database files ("DATA", "Data" and "data" types) in most instructions. This was made on purpose, to avoid any risk of performing dangerous actions on files or deleting programs on the devices.

Legend:

#v|n is the File Handle and is in the range [0...9]; this means that you can work with up to 10 files simultaneously
c|t is the name of the database file; do not put the ".pdb" extension in this name

CLOSE #v|n

Closes the file indicated by #v|n which has been previously opened by the OPEN statement, and releases the #v|n handle

Notes:

Raises a FILEERROR if the operation fails

$ COPY c|t1, c|t2[, c|t3]

Notes:

If file c|t2 already exists does nothing and raises a FILEERROR

Warning: you are allowed to copy databases with any Creator ID, this means that you can copy almost any database file (with "DATA", "Data" or "data" type) on your device.

INPUT #v|n, v|c

Reads data from an opened file with OPEN and moves to next record.

Notes:

Raises a FILEERROR if the operation fails
All data, even numerical values, is stored in text string format in the file (using PRINT #). So you may write a number and read it back in a text string

$ KILL c|t

Deletes the file specified by c|t

Warning: you are allowed to delete databases with any Creator ID, this means that you can delete almost any database file (with "DATA", "Data" or "data" type) on your device.

Notes:

Raises a FILEERROR if the operation fails

Makes file c|t available for sequential input, sequential output and reserves the #v|n handle for all read and write accesses to this file.

The FOR part of the instruction passes the file open mode:

INPUT sequential reading (with INPUT #), starting at first record

OUTPUT sequential writing (with PRINT #), erasing all content of file if any when opening it or creating it if does not exist

APPEND sequential writing, beginning at current end of file (see EOF function), creates the file if it does not exist

RANDOM random-access reading and writing (see SEEK statement), starting at first record, creates the file if it does not exist

Notes:

Raises a FILEERROR if the operation fails
To avoid any risk of deleting important files on your Palm device, the OUTPUT, APPEND and RANDOM file modes only work with databases having a "LDIB" Creator ID if the SECUREFILES compiling directive is set to ON
Be careful: if you erase iziBasic from your device, which has "LDIB" as a Creator ID, the standard Palm OS deletion mode will also erase all databases having a "LDIB" Creator ID
Would you wish to work on external files anyway (meaning not having a "LDIB" Creator ID), you may:
o either set the SECUREFILES compiling directive to OFF
o or do it in 3 steps by using the COPY instruction with "LDIB" as Creator ID for the destination file before using the OPEN instruction with this destination file. After you finish working on this file, CLOSE it. Then you may KILL the original file and COPY the destination back to the original one.

Warning: In the case you work on such databases, be careful that applications using categories may not work correctly afterwards! This is due to how Palm OS manages categories. In the case of the Memo Pad for instance, my own tests have shown that the APPEND mode works fine when the RANDOM mode would give unpredictable results.

PRINT #v|n, v|n|c|t

Writes data to file and moves to next record

Notes:

Raises a FILEERROR if the operation fails
In RANDOM mode, erases the current record and replaces it with the new one, unless the file pointer is at the end of file (see EOF function)
All data, even numerical values, is stored in text string format in the file. So you may write a number and read it back (using INPUT #) in a text string

$ RENAME c|t1, c|t2

Renames file from name c|t1 to name c|t2

Notes:

Raises a FILEERROR if the operation fails

Warning: you are allowed to rename databases with any Creator ID, this means that you can rename almost any database file (with "DATA", "Data" or "data" type) on your device.

$ RUN c|t1[, c|t2]

Exits from the current program and launches program c|t1 with a optional c|t2 string text parameter to pass to the new program

Notes:

if the program passed in parameter c|t1 does not exist, remains in the current program and you might then want to handle the error with FILEERROR in the lines following the RUN instruction…
the c|t2 parameter is passed to the new program which may retrieve it with the RUN$ function

$ SEEK #v|n1, v|n2

Sets file position to the given v|n2 record

Notes:

SEEK is available for files opened in INPUT or RANDOM modes

EOF(#v|n)

Returns if End Of File is reached (1=true/0=false)

Notes:

The current record number is the next record to read or write. For instance, if you just read the 3rd record (with the INPUT #v|n, v|c statement) out of 4 records, EOF will return true.
As a consequence, to parse all records of a database you should code something like this:
WHILE F=0
F=EOF(#1) : INPUT #1,A$ : PRINT A$
WEND

and not like this which will skip the last record:

WHILE F=0
INPUT #1,A$ : F=EOF(#1) : PRINT A$
WEND

FILEERROR

Returns if last file operation generated an error (1=true/0=false)

FILEEXISTS(c|t)

Returns 1=file exists or 0=file does not exist

FINDFIRST$(c|t1, c|t2)

Returns the name of the first file found which complies with the given parameters (see notes) or empty text string if none found

FINDFIRST$ works in conjunction with FINDNEXT$. You initiate a search for files with FINDFIRST$ and then search for all given files with FINDNEXT$ in a loop.

Notes:

c|t1 is a 4 characters Type (application, database...) of files to search for, pass empty text string to scan all types
c|t2 is a 4 characters CreatorID of files to search for, pass empty text string to scan all Creator IDs
scan for the next files complying with the search criteria using the FINDNEXT$ function

FINDNEXT$(c|t1, c|t2)

Returns the name of next file found which complies with the given parameters (see notes) or empty text string if none was found anymore

FINDNEXT$ works in conjunction with FINDFIRST$. You initiate a search for files with FINDFIRST$ and then search for all given files with FINDNEXT$ in a loop.

Notes:

c|t1 is Type and c|t2 is CreatorID of database to search for
be careful to pass the same parameters as for the FINDFIRST$ function, otherwise you will get unexpected results

Example of use:

' Scan for all iziBasic database files

F$=FINDFIRST$("DATA","LDIB")

WHILE F$<>""

PRINT F$

F$=FINDNEXT$("DATA","LDIB")

WEND

LOC(#v|n)

Returns Location in File = current record number

Notes:

The current record number is the next record to read or write. For instance, if you just read the 3rd record (with the INPUT #v|n, v|c statement), LOC will return 4.

LOF(#v|n)

Returns Length Of File = number of records

RUN$

Retrieves a string text parameter passed to the program.

Notes:

see the RUN statement